Aminet 6

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / dev / debug / apurify_v1_1.lha / apurify / doc / APurify.doc < prev next >

Wrap

Text File | 1995-04-10 | 14.5 KB | 308 lines

APurify ------- (c) by Samuel DEVULDER April 1995 Samuel.Devulder@info.unicaen.fr DESCRIPTION (SHORT): -------------------- APurify is a program that allows you to detect bad accesses to memory of your programs without any kind of specific external devices (MMU). It avoids bugs due to accessing memory not owned by your program. SYNOPSIS: -------- APurify [-revinfo] <Source file> [<Destination file>] APurify -revinfo To get informations about APurify (name, size and date of modules and number of compilation done for that version). APurify <Source file> <Destination file> Analyse the assembly language source file and generate a new file ready to be compiled and linked with APur.lib. Illegal access to memory of that file will be detected by APurify. Destination file can be the same as source file. APurify <Fichier source> Same as: APurify <Source file> <Source file>. eg: Destination filename is the same as the source filename. DESCRIPTION (A BIT LONGER): -------------------------- As a general rule, at the microprocessor level, there is two kind of ways to access memory. There is direct access and indirect access to memory. For example, in C, direct access can be viewed as accessing to global variables. Indirect access corresponds to accessing an array value. More precisely, direct access corresponds to reading or writing a variable whose address is known at compilation time (or since the loading of the program into the memory). Indirect access is used for variables whose adress is dynamicaly determined by the program. For example, if p is a pointer to an array allocated by malloc(), *p is an indirect access. Such an access occur also in case of instruction like T[i] where T is a global array, because the address of T[i] is not known at compilation time, since it depends on the index value i. Using indirect access to memory is called indirection. A regular program must not access memory not owned by it. That kind of access can be qualified as illegal. Illegal direct access to memory is not possible, because by definition, only global variables can be accessed that way and those variables belongs obviously to the program (except for code written in assembly language that references absolute values, for example: btst #6,$bfe001; but that kind of code can't be produced in C directly). So direct access to memory is always right. On the other hand, it is sure that indirect access to memory can be illegal. Many bugs are made by overstepping array boundaries. If that oversteppings are in reading a value, there is not much trouble; but if it is in writing, big mess can happen. APurify works on that kind of access by verifying the validity of indirect access to memory. It remebers the memory that was allocated by the program and check the integrity of each access. One can think that makes a lot of tests ! Well, yes, but APurify is not designed to be used in the general use of programs; just in test phases. Moreover, indirections do no occur very often actually. Only array-linked variables produces indirections. Thus, the variables on the stack ---although being accessed by indirection--- are not checked because their access is always safe (at least if there is no stack overflow !). Also, in SMALL_DATA model, global variables access is done through indirection, but they are not checked. If an illegal access is found, APurify displays an error message on the error stream of the program (have a look at the full justification of the output :^). There is two kind of illegal accesses. Some are accesses to memory that doesn't belong to the program (it is called an access between blocks), some others are accesses to a part of memory owned by a program and an other part not owned by it (it is an overstepping of a block). The memory is represented by a block. Each block is displayed according to the following pattern: [0x<n1>(<n2>) <attr> (<text>)] where <n1> is the hexadecimal address of the beginning of the block, <n2> its length, <attr> 3 status characters RWS where R means: read-enable block W means: write-enable block S means: system block (block not controlled by the program). If one access is forbidden, the letter '-' replaces the corresponding character. <text> is actually the name of the procedure that has allocated the block. If it ends with "*" that block was allocated by a call within the one indicated to a procedure not parsed by APurify (a library call, maybe). In case of an error, APurify displays the blocks that surrounds the illegal access and the number of bytes to those blocks. It also displays a block for the accessed address. In that block, the beginning address is the faultly address, the length is the size of the access (1 for a byte access, 2 for a short, 4 for a int/long and >4 for movem instruction). Attributes are R or W wether it's a read or write access. The text-field contains the name of the procedure in which the illegal access had happened. APurify checks the memory allocated but not freed by the program. (in fact, it detects non deallocated-blocks on library-closing time). It knows about memory location independant of the program execution. That is to say, the first kilobyte of memory that contains interrupt vectors of the 680x0 processor, the program segments and the stack. Accessing to those blocks will not be illegal. They got the S attribute (for SYSTEM blocks). It takes into account memory block allocated by malloc() and AllocMem(), and indirect allocated block (by OpenScreen() for example). But I did not test the last kind of allocation. Anyway, it should be ok, because APurify patches AllocMem() & FreeMem() entries. Thus a program can access to the bitplanes of one of its screen without error. If the program makes a legal access, but attributes are incompatible with the access-kind, a protection-error message is displayed. Actually only the first kilobyte is write-protected (so that one can read ExecBase). But it may change in the future. In order to speed up block searching, APurify uses a cache of recently accessed blocks. Thus, even if there is a large amount of memory blocks, execution should not be slowed down too much. USAGE: ----- One can see APurify as a pre-assembler. It must be used on assembly language sourcefile just before the assembler takes place. It scan the file and change it a bit so that APur.lib can be used. Normal way to use it for a C program is to: - compile C sourcefiles and leave assembly language source (.asm). - use APurify on each .asm file. - link all .o files together with APur.lib. As you can see, APurify needs no change to your C files to be used. However, the library must be opened by calling AP_Init() in the main() function and, *VERY IMPORTANT*, closed before exiting the program by calling AP_Close() (just before every exit() func-call, for example). As a matter of fact, since some system functions are patched, if a program exits without closing the library, you'll meet the guru (ie: the computer will crash)... (You've been warned :-). The easiest way to do this is to use atexit() (for example, by calling atexit(AP_Close) just after calling AP_Init()). If you forget to open the library, a warning message will tell you about that and the program will go on without APurify. You can disable/enable printing of messages by making a call to AP_Report(flag). If flag is true then printing is enabled, if it is false, no output will be done. This is usefull for startup-codes. For example, if you are using the argv[] array in C, APurify will make a lot of false-error printing. This is because the values pointed by this array is allocated before the library is opened. You can avoid this by calling AP_Report(0) before, and AP_Report(1) after, the code that uses argv[]. You can use APurify on any language that generates a temporary assembly language sourcefile (included assembly itself :-) ). You must notice too, that you can use it on programs for which no source-code is available (or .o files without .asm files). For that, use a program that makes reverse engineering on your executable (ie: that disassembles the executable and produces a .asm file ready to be assembled). Then, with minor changes (prepend '_' to every label, put calls AP_Init & AP_Close to right places), you get a file ready to be processed by APurify. When processing a file, APurify puts some func-calls and some extra data sections in the file. There are different syntax to insert new sections and to import new functions, according to the compiler. APurify find which syntax should be used by analysing the file. It knowns the pseudo-instructions dseg/csed & public (AZTEC) and section & xref/xef (DICE, HCC, ...). If a compiler uses the same instructions, you can use APurify with it (but it has just been tested with DICE !). The library APur.lib included is a DICE library. It can be used with other compilers if they know that kind of file (standard COMMODORE format). However, DICE uses a specific symbol for the stack base (ULONG *_ExitSP). If your compiler doesn't known that variable, you have to build it. For that, declare it as a global variable. Make it points to the return-to-system address pushed in the bottom of the stack by the system (ie: 8 bytes below stack base). And subtract 44 bytes. To sum up, use the following formula: ULONG *_ExitSP = (ULONG *)((char *)Process_Stack_Base - 8 - 44). Indeed, the stack base of a program (Process_Stack_Base) is not always the one indicated by the system flags (I don't know why...). However, you can compute it by using one of the global variables of your compiler. For example, the _exit() procedure should use a variable that points to the return-to-system address on stack. Then, the stack base is that address + 8 bytes. Now, you should adapt the formula to your compiler. If anyway, the library is not good, you can rebuild it: compile APfunc.c and APserv.a (modify them to your needs), and then join them together to create APur.lib. LEGAL PART: ---------- That program is provided 'AS IS'. I am not responsible for any dammage it can cause (but I am responsible for the benefits it can give to you :-). Use that software at you own risks. That program is FREEWARE. You can use and distribute it as long as you keep the archive intact (no adulteration of files except for compression). It can't be sold without my agreement (except a minimal amount for media support). You must ask me for commercial use of (any part of) that product. I keep all my rights on that program and its future releases. I can modify that software without telling it to the users. If you wish, you can send me a postcard or anything else you want (money, documentation, amiga, hardware stuff, ...) in exchange for using APurify. But there is no obligation :-). My postal address is: M. DEVULDER Samuel 1, Rue du chateau 59380 STEENE FRANCE (yes I'm french !). You can send suggestions or bugs to my email address: devulder@info.unicaen.fr DISTRIBUTION: ------------ That archive contains french and english version of APurify: - doc/APurify.doc: The file you are currently reading. - doc/APurify.doc.fre: French doc file. _/ - bin/APurify.fre: French version of the parser. | \ - bin/APurify: English version of the parser. | +-----> to be renamed as APurify according to your choice. _/ - lib/APur.lib.fre: French version of the library. | \ - lib/APur.lib: English version of the library. | +-----> to be renamed as APur.lib according to your choice. That library is in COMMODORE format (generated by DICE). _/ - lib/APserv.a | \ - lib/APfuncs.c | +-----> to re-build the library. - test/test.c: Source of a stupid test file - test/test.fre: Test file linked with APur.lib.fre - test/test: Test file linked with APur.lib. NOTES: ----- My configuration is: one old A500 (1989), 1Mo RAM, 1 diskdrive, KS1.3 and a lot of patience (ah, I wish I had an A4000/040/33Mhz !). I had the idea of that program after a chat with Cedric BEUST (AMIGA NEWS) on IRC (Internet Relay Chat). Thanks Cedric ! All marks are proprietary of their respective owners. APurify has been compiled with netdcc, the non-registered version of DICE, by Matt DILLON. The parser is build from the TOP optimizer of HCC distribution ((c) Sozobon ltd, Tony Andrews & Detlef Wuerkner). There are some programs like APurify. For example, FORTIFY (Simon P. Bullen), but it only detects illegal writes to boundaries of allocated blocks. Thus it can't detect big oversteps and oversteps in reading and the detection is not real-time. Enforcer can detect illegal access to memory (I think), but it needs a special device (MMU). BUGS: ---- APurify don't known public memory where a program can read or write without having allocated it. Thus, it will report an error when a program reads or writes values in a message obtained through GetMsg() calls. It can only scan 68000 codes. If the sourcefile contains instructions for 680x0 (x>1) processors, it will complain (at least for new adressing modes). That will change if I found the source of a 680x0 (x>1) assembler (but I need time, and you're welcome to tell me that you got one). It can display messages about closing the library without freeing some memory blocks. This is due to printf() that allocates memory that is free'd on exit. This is not a real bug, but you can avoid this by doing a AP_Report(0) just before exiting. But you must notice that it is better to display false bugs than to not display real ones. Certainly more bugs, but I'm waiting for your bug-reports.